home *** CD-ROM | disk | FTP | other *** search
/ Archive Magazine CD 1995 / Archive Magazine CD 1995.iso / discs / prog_disc / volume_8 / issue_06 / risc_os / Wimp / Pointer < prev    next >
Encoding:
Text File  |  1988-12-06  |  4.5 KB  |  117 lines
  1. > Wimp.Pointer
  2.  
  3. New Calls
  4. ---------
  5.  
  6.         *Pointer
  7.         Wimp_SetPointerShape
  8.         Wimp_SpriteOp (36 = SetPointerShape)
  9.         how to behave properly
  10.  
  11.  
  12. *Pointer
  13. --------
  14.  
  15.         Syntax:  *Pointer [0 | 1]
  16.  
  17. *Pointer or *Pointer 1 turns the pointer on, while *Pointer 0 turns it off.
  18.  
  19. The *Pointer command has been changed so that it sets up the default pointer
  20. shape in mouse pointer 1 from a sprite called "ptr_default" in the Wimp's
  21. common sprite pool (see Wimp.Sprites).
  22.  
  23. The default pointer sprite does not contain a palette - instead, *Pointer
  24. sets the pointer palette from the current setting of the Wimp palette (see
  25. Wimp.Colours).
  26.  
  27. Applications wishing to alter the pointer shape while the pointer is inside
  28. their window should use pointer shape 2, and should reset the pointer using
  29. the *Pointer command when the pointer leaves the window.
  30.  
  31. Pointer shapes 3 and 4 are reserved for use by such programs as the Hourglass
  32. module, which modifies the pointer shape under interrupt.
  33.  
  34.  
  35. Wimp_SetPointerShape
  36. --------------------
  37.  
  38. Entry:  R0 = pointer shape number (0 to turn it off)
  39.         R1 -> shape data (2 bits per pixel, rows from top to bottom)
  40.         R2 = width (pixels)
  41.         R3 = height (pixels)
  42.         R4,R5 = offset of active point from top-left
  43.  
  44. The use of this call is now discouraged, as there is a better one:
  45.  
  46.  
  47. Wimp_SpriteOp, R0 = 36 (SetPointerShape)
  48. ----------------------------------------
  49.  
  50. Entry:  R0 = 36
  51.         R2 -> sprite name (of the form "ptr_xxx")
  52.         R3 bits 0..3 = pointer shape number
  53.         R3 bit 4 set => don't set up the shape data
  54.         R3 bit 5 set => don't set up the palette
  55.         R3 bit 6 set => don't set up the pointer shape number
  56.         R4,R5 = coordinates of active point from top-left
  57.         R6 -> scale factors (as for PutSpriteScaled)
  58.         R7 -> translation table  (as for PutSpriteScaled)
  59.  
  60.         (see also Wimp.SprExtend).
  61.  
  62. If R3 bit 5 is unset, but the sprite has no palette entries, the Wimp will
  63. set up the default pointer palette (ie. the one that the Palette utility can
  64. alter).
  65.  
  66. The convention for pointer shapes is that there should be a well-known
  67. 'family' of them in the Wimp's common sprite area, and applications should
  68. use these if possible.  In this way many applications can share data, and it
  69. also makes it easier for the user to change the pointer shapes if he so
  70. desires.  Another advantage is that the various pointer shapes are more
  71. likely to coordinate with each other.
  72.  
  73. The default pointer shapes all have names starting with "ptr_": the list so
  74. far is as follows:
  75.  
  76.         ptr_default             default pointer shape
  77.  
  78. Note that if for some reason it is not desirable to use a pointer shape from
  79. the Wimp's common sprite pool, it is possible to call OS_SpriteOp directly to
  80. use any arbitrary sprite as a pointer shape.
  81.  
  82.  
  83. How to behave properly
  84. ----------------------
  85.  
  86. The recommended way for applications to change the pointer shape is for them
  87. to trap Pointer_Entering_Window and Pointer_Leaving_Window events from
  88. Wimp_Poll, setting up pointer shape 2 when the pointer enters their window,
  89. and restoring to pointer shape 1 when the pointer leaves the window (NB: the
  90. recommended way to do this is by *Pointer, since that resets the mouse
  91. palette as well).
  92.  
  93. There are some pitfalls, however:
  94.  
  95.      *  The application must keep a flag saying whether the pointer is
  96.         currently inside its window, so that if it wants to change the
  97.         pointer shape due to some internal state change, it should only do so
  98.         if it currently 'owns' the pointer.  The classic case of this is when
  99.         the user right-clicks in a menu on the window, causing the
  100.         application to change what it wants the pointer shape to be. 
  101.         Unfortunately if the menus are re-opened immediately, the pointer
  102.         should remain in its default state, since it never enters the
  103.         application window.
  104.  
  105.      *  When the user alters the screen mode (ie. Wimp_SetMode is called),
  106.         the pointer shape is set back to the default.  However, no
  107.         Pointer_Entering or Pointer_Leaving events are generated, so the
  108.         application must explicitly reset the correct pointer shape when it
  109.         gets the Message_ModeChange message, if it thinks that it currently
  110.         owns the pointer (see above).
  111.  
  112. The latter case is currently difficult to elicit, since the only way for the
  113. user to change mode is via the palette utility's menu.  However, if someone
  114. were to invent a 'hot key' that called Wimp_SetMode, the pointer could be
  115. anywhere at the time, so applications should be written to cope with it.
  116.  
  117.